---
title: 뷰 전환 라우터 API 참조
sidebar:
  label: 'astro:transitions'
i18nReady: true
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 6
---
import Since from '~/components/Since.astro';
import ReadMore from '~/components/ReadMore.astro';

<p><Since v="3.0.0" /></p>

이 모듈은 뷰 전환 API 및 클라이언트 측 라우터를 제어하고 상호 작용하는 함수를 제공합니다.

:::note
이 API는 `astro:transitions`에 포함된 `<ClientRouter />`와 호환되지만, 네이티브 브라우저 MPA 라우팅과는 함께 사용할 수 없습니다.
:::

기능 및 사용 예시는 [뷰 전환 가이드](/ko/guides/view-transitions/)를 참조하세요.

## `astro:transitions`에서 가져오기

```ts
import { ClientRouter, fade, slide } from 'astro:transitions';
```

### `<ClientRouter />`

<p><Since v="3.0.0" /></p>

원하는 모든 페이지의 `<head>`에 `<ClientRouter />` 라우팅 컴포넌트를 가져오고 추가하여 개별 페이지에서 트랜지션을 사용하도록 선택합니다.

```astro title="src/pages/index.astro" ins={2,7}
---
import { ClientRouter } from 'astro:transitions';
---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ClientRouter />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>
```

페이지 요소와 컴포넌트에 [라우터 제어](/ko/guides/view-transitions/#라우터-제어) 및 [전환 지시어를 추가](/ko/guides/view-transitions/#전환-지시어)하는 방법에 대해 자세히 알아보세요.

### `fade`

<p>

**타입:** `(opts: { duration?: string | number }) => TransitionDirectionalAnimations`
<Since v="3.0.0" />
</p>

기본적으로 제공되는 `fade` 애니메이션의 지속 시간을 설정할 수 있는 유틸리티 함수입니다.

```astro {2} /fade\\(.+\\)/
---
import { fade } from 'astro:transitions';
---

<!-- 기본 지속 시간을 사용한 페이드 트랜지션 -->
<div transition:animate="fade" />

<!-- 400 밀리초 동안 지속되는 페이드 트랜지션 -->
<div transition:animate={fade({ duration: '0.4s' })} />
```

### `slide`

<p>

**타입:** `(opts: { duration?: string | number }) => TransitionDirectionalAnimations`
<Since v="3.0.0" />
</p>

기본적으로 제공되는 `slide` 애니메이션의 지속 시간을 설정할 수 있는 유틸리티 함수입니다.

```astro {2} /slide\\(.+\\)/
---
import { slide } from 'astro:transitions';
---

<!-- 기본 지속 시간을 사용한 슬라이드 트랜지션 -->
<div transition:animate="slide" />

<!-- 400 밀리초 동안 지속되는 슬라이드 트랜지션 -->
<div transition:animate={slide({ duration: '0.4s' })} />
```

## `astro:transitions/client`에서 가져오기

```astro
<script>
  import {
    navigate,
    supportsViewTransitions,
    transitionEnabledOnThisPage,
    getFallback,
    swapFunctions,
  } from 'astro:transitions/client';
</script>
```

### `navigate()`

<p>

**타입:** `(href: string, options?: Options) => void`<br />
<Since v="3.2.0" />
</p>

뷰 전환 API를 사용하여 지정된 `href`로 탐색을 실행하는 함수입니다.

이 함수 시그니처는 [브라우저 Navigation API의 `navigate` 함수](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate)를 기반으로 합니다. 이 함수는 Navigation API를 기반으로 하지만, 페이지를 다시 로드하지 않고 탐색할 수 있도록 [History API](https://developer.mozilla.org/ko/docs/Web/API/History_API) 위에 구현되어 있습니다.

`navigate()`는 `href` 매개변수에 대한 검증을 수행하지 않습니다. 이동할 URL을 결정하기 위해 사용자 입력을 사용하는 경우 [사용자 입력을 검증](/ko/guides/view-transitions/#사용자-입력을-통해-탐색하기)하세요.

#### `history` 옵션

<p>

**타입:** `'auto' | 'push' | 'replace'`<br />
**기본값:** `'auto'`<br />
<Since v="3.2.0" />
</p>

이 탐색을 브라우저 기록에 추가하는 방법을 정의합니다.

- `'push'`: 라우터는 `history.pushState`를 사용하여 브라우저 기록에 새 항목을 생성합니다.
- `'replace'`: 라우터는 `history.replaceState`를 사용하여 탐색에 새 항목을 추가하지 않고 URL을 업데이트합니다.
- `'auto'` (기본값): 라우터는 `history.pushState`를 시도하지만, URL을 전환할 수 없는 경우 현재 URL은 브라우저 기록을 변경하지 않고 그대로 유지됩니다.

이 옵션은 브라우저 Navigation API의 [`history` 옵션](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#history)을 따르지만, Astro 프로젝트에서 발생할 수 있는 경우를 위해 단순화되었습니다.

#### `formData` 옵션

<p>

**타입:** `FormData`<br />
<Since v="3.5.0" />
</p>

`POST` 요청을 위한 `FormData` 객체입니다.

이 옵션을 제공하면 탐색 대상 페이지에 대한 요청이 양식 데이터 객체를 콘텐츠로 하는 `POST` 요청으로 전송됩니다.

트랜지션이 활성화된 HTML 양식을 제출하면 페이지 새로 고침이 있는 기본 탐색 대신 이 메서드가 사용됩니다. 이 메서드를 호출하면 프로그래밍 방식으로 동일한 동작을 트리거할 수 있습니다.

#### `info` 옵션

<p>

**타입:** `any`<br />
<Since v="3.6.0" />
</p>

이 탐색으로 인해 발생하는 `astro:before-preparation` 및 `astro:before-swap` 이벤트에 포함될 임의의 데이터입니다.

이 옵션은 브라우저 Navigation API의 [`info` 옵션](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#info)을 모방합니다.

#### `state` 옵션

<p>

**타입:** `any`<br />
<Since v="3.6.0" />
</p>

이 탐색에서 생성된 `NavitationHistoryEntry` 객체에 연결할 임의의 데이터입니다. 이 데이터는 History API의 [`history.getState` 함수](https://developer.mozilla.org/en-US/docs/Web/API/NavigationHistoryEntry/getState)를 사용하여 검색할 수 있습니다.

이 옵션은 브라우저 Navigation API의 [`state` 옵션](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#state)을 모방합니다.

#### `sourceElement` 옵션

<p>

**타입:** `Element`<br />
<Since v="3.6.0" />
</p>

존재하는 경우, 이 탐색을 트리거한 요소입니다. 이 요소는 다음 이벤트에서 사용할 수 있습니다:
- `astro:before-preparation`
- `astro:before-swap`

### `supportsViewTransitions`

<p>

**타입:** `boolean`<br />
<Since v="3.2.0" />
</p>

현재 브라우저에서 트랜지션이 지원되고 활성화되어 있는지 여부입니다.

### `transitionEnabledOnThisPage`

<p>

**타입:** `boolean`<br />
<Since v="3.2.0" />
</p>

현재 페이지에 클라이언트 측 탐색을 위한 트랜지션이 활성화되어 있는지 여부입니다. 트랜지션이 있는 페이지에서 다르게 동작하는 컴포넌트를 만드는 데 사용할 수 있습니다.

### `getFallback()`

<p>

**타입:** `() => 'none' | 'animate' | 'swap'`<br />
<Since v="3.6.0" />
</p>

트랜지션을 지원하지 않는 브라우저에서 사용할 대체 전략을 반환합니다.

대체 동작을 선택하고 구성하는 방법은 [대체 제어](/ko/guides/view-transitions/#대체-옵션) 가이드를 참조하세요.

### `swapFunctions`

<p>

<Since v="4.15.0" />
</p>

Astro의 기본 교체 함수를 빌드하는 데 사용되는 유틸리티 함수가 포함된 객체입니다.
[사용자 정의  함수를 만들때](/ko/guides/view-transitions/#사용자-정의-교체-함수-구현) 유용할 수 있습니다.

`swapFunctions`는 다음과 같은 메서드를 제공합니다:

#### `deselectScripts()`

<p>

**타입:** `(newDocument: Document) => void`
</p>

새 문서에서 실행해서는 안 되는 스크립트를 표시합니다. 이러한 스크립트는 이미 현재 문서에 있으며 [`data-astro-rerun`](/ko/guides/view-transitions/#data-astro-rerun)을 사용하여 다시 실행하도록 플래그가 지정되지 않습니다.

#### `swapRootAttributes()`

<p>

**타입:** `(newDocument: Document) => void`
</p>

`lang` 속성과 같은 문서 루트 간 속성을 교체합니다. 여기에는 `data-astro-transition`과 같은 Astro에서 삽입한 내부 속성도 포함되어 있어, 트랜지션 방향을 Astro에서 생성된 CSS 규칙에 사용할 수 있습니다.

사용자 정의 교체 함수를 만들 때, 트랜지션의 애니메이션이 깨지지 않도록 이 함수를 호출하는 것이 중요합니다.

#### `swapHeadElements()`

<p>

**타입:** `(newDocument: Document) => void`
</p>

현재 문서의 `<head>`에서 새 문서에 유지되지 않는 모든 요소를 제거합니다. 그런 다음 새 문서의 `<head>`에 있는 모든 새 요소를 현재 문서의 `<head>`에 추가합니다.

#### `saveFocus()`

<p>

**타입:** `() => () => void`
</p>

현재 페이지에서 포커스된 요소를 저장하고, 포커스된 요소가 유지되는 경우, 호출 시 해당 요소에 포커스를 제공하는 함수를 반환합니다.


#### `swapBodyElement()`

<p>

**타입:** `(newBody: Element, oldBody: Element) => void`
</p>

이전 body를 새 body로 교체합니다. 그런 다음 이전 body에서 유지되어야 하는 모든 요소를 검토하고 새 body에서 일치하는 요소를 찾아 이전 요소를 다시 제자리로 바꿉니다.

## 라이프사이클 이벤트

### `astro:before-preparation` 이벤트

뷰 전환 라우터를 사용하여 탐색을 시작할 때 전송되는 이벤트입니다. 이 이벤트는 요청이 이루어지고 브라우저 상태가 변경되기 전에 발생합니다.

이 이벤트에는 속성이 있습니다:
- [`info`](#info)
- [`sourceElement`](#sourceelement)
- [`navigationType`](#navigationtype)
- [`direction`](#direction)
- [`from`](#from)
- [`to`](#to)
- [`formData`](#formdata)
- [`loader()`](#loader)

이 이벤트의 사용 방법에 대한 자세한 내용은 [뷰 전환 가이드](/ko/guides/view-transitions/#astrobefore-preparation)에서 확인하세요.

### `astro:after-preparation` 이벤트

뷰 전환 라우터를 사용하는 탐색에서 다음 페이지가 로드된 후 전송되는 이벤트입니다.

이 이벤트에는 속성이 없습니다.

이 이벤트의 사용 방법에 대한 자세한 내용은 [뷰 전환 가이드](/ko/guides/view-transitions/#astroafter-preparation)에서 확인하세요.

### `astro:before-swap` 이벤트

다음 페이지가 구문 분석되고, 준비되고, 트랜지션을 준비하면서 문서에 링크된 후, 문서 간 콘텐츠가 교환되기 전에 전송되는 이벤트입니다.

이 이벤트는 취소할 수 없습니다. `preventDefault()`를 호출하는 것은 아무 작업도 하지 않습니다.

이 이벤트에는 속성이 있습니다:
- [`info`](#info)
- [`sourceElement`](#sourceelement)
- [`navigationType`](#navigationtype)
- [`direction`](#direction)
- [`from`](#from)
- [`to`](#to)
- [`viewTransition`](#viewtransition)
- [`swap()`](#swap)

이 이벤트의 사용 방법에 대한 자세한 내용은 [뷰 전환 가이드](/ko/guides/view-transitions/#astrobefore-swap)에서 확인하세요.

### `astro:after-swap` 이벤트

페이지의 콘텐츠가 교체된 후, 트랜지션이 끝나기 전에 전달되는 이벤트입니다.

기록 항목과 스크롤 위치가 업데이트된 후, 이 이벤트가 트리거됩니다.

### `astro:page-load` 이벤트

트랜지션을 사용하는 탐색이나 브라우저의 기본 기능으로 페이지 로드가 완료된 후 전달되는 이벤트입니다.

페이지에서 트랜지션이 활성화되면 일반적으로 `DOMContentLoaded`에서 실행되는 코드가 이 이벤트에서 실행되도록 변경되어야 합니다.

### 라이프사이클 이벤트 속성

<p><Since v="3.6.0" /></p>

#### `info`

<p>

**타입:** `URL`
</p>

탐색 중에 정의된 임의의 데이터입니다.

이는 [`navigate()` 함수](#navigate)의 [`info` 옵션](#info-옵션)에 전달된 리터럴 값입니다.

#### `sourceElement`

<p>

**타입:** `Element | undefined`
</p>

탐색을 트리거한 요소입니다. 예를 들어 클릭된 `<a>` 요소가 될 수 있습니다.

[`navigate()` 함수](#navigate)를 사용할 때는 호출에서 지정된 요소가 됩니다.

#### `newDocument`

<p>

**타입:** `Document`
</p>

탐색의 다음 페이지에 대한 문서입니다. 이 문서의 내용은 현재 문서의 내용 대신 교체됩니다.

#### `navigationType`

<p>

**타입:** `'push' | 'replace' | 'traverse'`
</p>

어떤 종류의 기록 탐색이 일어나고 있나요.
- `push`: 새 페이지에 대한 새 `NavigationHistoryEntry`가 만들어지고 있습니다.
- `replace`: 현재 `NavigationHistoryEntry`가 새 페이지의 항목으로 대체되고 있습니다.
- `traverse`: `NavigationHistoryEntry`이 생성되지 않습니다. 히스토리 내 위치가 변경되고 있습니다.
  순회 방향은 [`direction` 속성](#direction)에서 지정됩니다.

#### `direction`

<p>

**타입:** `Direction`
</p>

트랜지션 방향입니다.
- `forward`: 기록의 다음 페이지 또는 새 페이지로 이동합니다.
- `back`: 기록의 이전 페이지로 이동합니다.
- 다른 리스너가 설정했을 수 있는 기타 모든 항목.

#### `from`

<p>

**타입:** `URL`
</p>

The URL of the page initiating the navigation.
탐색을 시작하는 페이지의 URL입니다.

#### `to`

<p>

**타입:** `URL`
</p>

탐색 중인 페이지의 URL입니다. 이 속성을 수정할 수 있으며, 라이프사이클이 끝날 때의 값이 다음 페이지의 `NavigationHistoryEntry`에 사용됩니다.

#### `formData`

<p>

**타입:** `FormData | undefined`
</p>

`POST` 요청을 위한 `FormData` 객체입니다.

이 속성을 설정하면 일반적인 `GET` 요청 대신 지정된 양식 데이터 객체를 콘텐츠로 하는 `POST` 요청이 [`to` URL](#to)로 전송됩니다.

트랜지션이 활성화된 HTML 양식을 제출할 때 이 필드는 양식의 데이터로 자동 설정됩니다. [`navigate()` 함수](#navigate)를 사용하는 경우 이 값은 옵션에 지정된 것과 동일합니다.

#### `loader()`

<p>

**타입:** `() => Promise<void>`
</p>

탐색에서 다음 단계 (다음 페이지 로딩)를 구현합니다. 이 구현을 재정의하여 동작을 추가할 수 있습니다.

#### `viewTransition`

<p>

**타입:** [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition)
</p>

이 탐색에 사용된 트랜지션 객체입니다. [뷰 전환 API](https://developer.mozilla.org/ko/docs/Web/API/View_Transitions_API)를 지원하지 않는 브라우저에서는 편의를 위해 동일한 API를 구현하지만 DOM 통합이 없는 객체입니다.

#### `swap()`

<p>

**타입:** `() => void`
</p>

문서 교체 로직을 구현합니다.

[사용자 지정 교체 함수를 구현](/ko/guides/view-transitions/#사용자-정의-교체-함수-구현)하는 방법에 대한 자세한 내용은 뷰 전환 가이드를 참조하세요.

기본적으로 이 구현은 다음 함수를 순서대로 호출합니다:

1. [`deselectScripts()`](#deselectscripts)
2. [`swapRootAttributes()`](#swaprootattributes)
3. [`swapHeadElements()`](#swapheadelements)
4. [`saveFocus()`](#savefocus)
5. [`swapBodyElement()`](#swapbodyelement)
